<!DOCTYPE html>
<html lang="en">
<head>
  <title>Buffers - Vert.x</title>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta content="width=device-width, initial-scale=1.0" name="viewport">
  <meta content="Vert.x is a tool-kit for building reactive applications on the JVM." name="description">
  <link href="http://vertx.io/stylesheets/docs.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/stylesheets/font-awesome.min.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/javascripts/styles/rainbow.min.css" media="screen" rel="stylesheet">
  <!-- IE 6-8 support of HTML 5 elements -->
  <!--[if lt IE 9]>
  <script src="http://static.jboss.org/theme/js/libs/html5/pre3.6/html5.min.js"></script>
  <![endif]-->

  <link rel="apple-touch-icon" sizes="57x57" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-57x57.png">
  <link rel="apple-touch-icon" sizes="60x60" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-60x60.png">
  <link rel="apple-touch-icon" sizes="72x72" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-72x72.png">
  <link rel="apple-touch-icon" sizes="76x76" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-76x76.png">
  <link rel="apple-touch-icon" sizes="114x114" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-114x114.png">
  <link rel="apple-touch-icon" sizes="120x120" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-120x120.png">
  <link rel="apple-touch-icon" sizes="144x144" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-144x144.png">
  <link rel="apple-touch-icon" sizes="152x152" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-152x152.png">
  <link rel="apple-touch-icon" sizes="180x180" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-180x180.png">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-32x32.png" sizes="32x32">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/android-chrome-192x192.png" sizes="192x192">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-96x96.png" sizes="96x96">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-16x16.png" sizes="16x16">
  <link rel="manifest" href="http://vertx.io/assets/favicons/vertx-favicon-7/manifest.json">
  <link rel="mask-icon" href="http://vertx.io/assets/favicons/vertx-favicon-7/safari-pinned-tab.svg" color="#5bbad5">
  <meta name="msapplication-TileColor" content="#7d3194">
  <meta name="msapplication-TileImage" content="http://vertx.io/assets/favicons/vertx-favicon-7/mstile-144x144.png">
  <meta name="theme-color" content="#ffffff">

  <link href="http://fonts.googleapis.com/css?family=Ubuntu:400,500,700,400italic" rel="stylesheet" type="text/css">
  <link rel="alternate" type="application/rss+xml" title="RSS"
     href="http://vertx.io/feed.xml">
  <script>
    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
    ga('create', 'UA-30144458-1', 'auto');
    ga('create', 'UA-71153120-1', 'auto', 'tracker');
    ga('send', 'pageview');
    ga('tracker.send', 'pageview');
  </script>
</head>
<body>

<a href="http://www.reactivemanifesto.org/" id="reactive-manifesto-banner">
  <img style="border: 0; position: fixed; right: 0; top:0; z-index: 9000"
    src="http://d379ifj7s9wntv.cloudfront.net/reactivemanifesto/images/ribbons/we-are-reactive-black-right.png">
</a>

<a id="skippy" class="sr-only sr-only-focusable" href="#content"><div class="container"><span class="skiplink-text">Skip to main content</span></div></a>

<header class="navbar navbar-default navbar-static-top" id="top" role="banner">
  <div class="container">
    <div class="navbar-header">
      <button class="navbar-toggle collapsed" type="button" data-toggle="collapse" data-target="#vertx-navbar-collapse">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <a href="http://vertx.io/" class="navbar-brand"><img alt="Brand" src="http://vertx.io/assets/logo-sm.png"></a>
    </div>
    <nav class="collapse navbar-collapse" id="vertx-navbar-collapse">
      <ul class="nav navbar-nav navbar-right">
        <li><a href="http://vertx.io/download/">Download</a></li>
        <li><a href="http://vertx.io/docs/">Documentation</a></li>
        <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
        <li><a href="http://vertx.io/community/">Community</a></li>
        <li><a href="http://vertx.io/materials/">Materials</a></li>
        <li><a href="http://vertx.io/blog/">Blog</a></li>        
      </ul>
    </nav>
  </div>
</header>



  <div class="page-header" id="content">
    <div class="container">
      <div class="row">
        <div class="col-sm-12">
          <h1>Buffers</h1>
          
        </div>
      </div>
    </div>
  </div>




<div id="content">
  <div class="container docs-content">
    <div class="row">
      <div class="col-sm-12 col-md-push-9 col-md-3 hidden-xs hidden-sm">
        <div id="sidebar" data-spy="affix">
          <ul class="sectlevel1">
<li><a href="#_buffers">Buffers</a>
<ul class="sectlevel2">
<li><a href="#_creating_buffers">Creating buffers</a></li>
<li><a href="#_writing_to_a_buffer">Writing to a Buffer</a></li>
<li><a href="#_reading_from_a_buffer">Reading from a Buffer</a></li>
<li><a href="#_working_with_unsigned_numbers">Working with unsigned numbers</a></li>
<li><a href="#_buffer_length">Buffer length</a></li>
<li><a href="#_copying_buffers">Copying buffers</a></li>
<li><a href="#_slicing_buffers">Slicing buffers</a></li>
<li><a href="#_buffer_re_use">Buffer re-use</a></li>
</ul>
</li>
</ul>
        </div>
      </div>
      <div class="col-sm-12 col-md-pull-3 col-md-9">
        <div class="toc hidden-md hidden-lg">
          <h2>Table of Contents</h2>
          <ul class="sectlevel1">
<li><a href="#_buffers">Buffers</a>
<ul class="sectlevel2">
<li><a href="#_creating_buffers">Creating buffers</a></li>
<li><a href="#_writing_to_a_buffer">Writing to a Buffer</a></li>
<li><a href="#_reading_from_a_buffer">Reading from a Buffer</a></li>
<li><a href="#_working_with_unsigned_numbers">Working with unsigned numbers</a></li>
<li><a href="#_buffer_length">Buffer length</a></li>
<li><a href="#_copying_buffers">Copying buffers</a></li>
<li><a href="#_slicing_buffers">Slicing buffers</a></li>
<li><a href="#_buffer_re_use">Buffer re-use</a></li>
</ul>
</li>
</ul>
        </div>
        <div class="sect1">
<h2 id="_buffers">Buffers</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Most data is shuffled around inside Vert.x using buffers.</p>
</div>
<div class="paragraph">
<p>A buffer is a sequence of zero or more bytes that can read from or written to and which expands automatically as
necessary to accommodate any bytes written to it. You can perhaps think of a buffer as smart byte array.</p>
</div>
<div class="sect2">
<h3 id="_creating_buffers">Creating buffers</h3>
<div class="paragraph">
<p>Buffers can create by using one of the static <code><a href="../../groovydoc/io/vertx/groovy/core/buffer/Buffer.html#buffer()">Buffer.buffer</a></code> methods.</p>
</div>
<div class="paragraph">
<p>Buffers can be initialised from strings or byte arrays, or empty buffers can be created.</p>
</div>
<div class="paragraph">
<p>Here are some examples of creating buffers:</p>
</div>
<div class="paragraph">
<p>Create a new empty buffer:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-groovy" data-lang="groovy">import io.vertx.groovy.core.buffer.Buffer
def buff = Buffer.buffer()</code></pre>
</div>
</div>
<div class="paragraph">
<p>Create a buffer from a String. The String will be encoded in the buffer using UTF-8.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-groovy" data-lang="groovy">import io.vertx.groovy.core.buffer.Buffer
def buff = Buffer.buffer("some string")</code></pre>
</div>
</div>
<div class="paragraph">
<p>Create a buffer from a String: The String will be encoded using the specified encoding, e.g:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-groovy" data-lang="groovy">import io.vertx.groovy.core.buffer.Buffer
def buff = Buffer.buffer("some string", "UTF-16")</code></pre>
</div>
</div>
<div class="paragraph">
<p>Create a buffer with an initial size hint. If you know your buffer will have a certain amount of data written to it
you can create the buffer and specify this size. This makes the buffer initially allocate that much memory and is
more efficient than the buffer automatically resizing multiple times as data is written to it.</p>
</div>
<div class="paragraph">
<p>Note that buffers created this way <strong>are empty</strong>. It does not create a buffer filled with zeros up to the specified size.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-groovy" data-lang="groovy">import io.vertx.groovy.core.buffer.Buffer
def buff = Buffer.buffer(10000)</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_writing_to_a_buffer">Writing to a Buffer</h3>
<div class="paragraph">
<p>There are two ways to write to a buffer: appending, and random access.
In either case buffers will always expand automatically to encompass the bytes. It&#8217;s not possible to get
an <code>IndexOutOfBoundsException</code> with a buffer.</p>
</div>
<div class="sect3">
<h4 id="_appending_to_a_buffer">Appending to a Buffer</h4>
<div class="paragraph">
<p>To append to a buffer, you use the <code>appendXXX</code> methods.
Append methods exist for appending various different types.</p>
</div>
<div class="paragraph">
<p>The return value of the <code>appendXXX</code> methods is the buffer itself, so these can be chained:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-groovy" data-lang="groovy">import io.vertx.groovy.core.buffer.Buffer
def buff = Buffer.buffer()

buff.appendInt(123).appendString("hello\n")

socket.write(buff)</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_random_access_buffer_writes">Random access buffer writes</h4>
<div class="paragraph">
<p>You can also write into the buffer at a specific index, by using the <code>setXXX</code> methods.
Set methods exist for various different data types. All the set methods take an index as the first argument - this
represents the position in the buffer where to start writing the data.</p>
</div>
<div class="paragraph">
<p>The buffer will always expand as necessary to accommodate the data.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-groovy" data-lang="groovy">import io.vertx.groovy.core.buffer.Buffer
def buff = Buffer.buffer()

buff.setInt(1000, 123)
buff.setString(0, "hello")</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_reading_from_a_buffer">Reading from a Buffer</h3>
<div class="paragraph">
<p>Data is read from a buffer using the <code>getXXX</code> methods. Get methods exist for various datatypes.
The first argument to these methods is an index in the buffer from where to get the data.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-groovy" data-lang="groovy">import io.vertx.groovy.core.buffer.Buffer
def buff = Buffer.buffer()
for (def i = 0;i &lt; buff.length();4) {
  println("int value at ${i} is ${buff.getInt(i)}")
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_working_with_unsigned_numbers">Working with unsigned numbers</h3>
<div class="paragraph">
<p>Unsigned numbers can be read from or appended/set to a buffer with the <code>getUnsignedXXX</code>,
<code>appendUnsignedXXX</code> and <code>setUnsignedXXX</code> methods. This is useful when implementing a codec for a
network protocol optimized to minimize bandwidth consumption.</p>
</div>
<div class="paragraph">
<p>In the following example, value 200 is set at specified position with just one byte:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-groovy" data-lang="groovy">import io.vertx.groovy.core.buffer.Buffer
def buff = Buffer.buffer(128)
def pos = 15
buff.setUnsignedByte(pos, 200)
println(buff.getUnsignedByte(pos))</code></pre>
</div>
</div>
<div class="paragraph">
<p>The console shows '200'.</p>
</div>
</div>
<div class="sect2">
<h3 id="_buffer_length">Buffer length</h3>
<div class="paragraph">
<p>Use <code><a href="../../groovydoc/io/vertx/groovy/core/buffer/Buffer.html#length()">length</a></code> to obtain the length of the buffer.
The length of a buffer is the index of the byte in the buffer with the largest index + 1.</p>
</div>
</div>
<div class="sect2">
<h3 id="_copying_buffers">Copying buffers</h3>
<div class="paragraph">
<p>Use <code><a href="../../groovydoc/io/vertx/groovy/core/buffer/Buffer.html#copy()">copy</a></code> to make a copy of the buffer</p>
</div>
</div>
<div class="sect2">
<h3 id="_slicing_buffers">Slicing buffers</h3>
<div class="paragraph">
<p>A sliced buffer is a new buffer which backs onto the original buffer, i.e. it does not copy the underlying data.
Use <code><a href="../../groovydoc/io/vertx/groovy/core/buffer/Buffer.html#slice()">slice</a></code> to create a sliced buffers</p>
</div>
</div>
<div class="sect2">
<h3 id="_buffer_re_use">Buffer re-use</h3>
<div class="paragraph">
<p>After writing a buffer to a socket or other similar place, they cannot be re-used.</p>
</div>
</div>
</div>
</div>

        

        
          <div id="footer">
            <div id="footer-text">
              
                Last updated 2016-09-12 08:38:04 CEST
              
              
            </div>
          </div>
        
      </div>
    </div>
  </div>
</div>

<footer>
  <div class="container">
    <div class="row">
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Vert.x</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/">Home</a></li>
          <li><a href="http://vertx.io/download/">Download</a></li>
          <li><a href="http://vertx.io/docs/">Documentation</a></li>
          <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
          <li><a href="http://vertx.io/blog/">Blog</a></li>
          <li><a href="http://vertx.io/vertx2/" class="vertx-2-link">Vert.x 2</a></li>
        </ul>
      </div>
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Community</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/community/">Help &amp; Contributors</a></li>
          <li><a href="http://vertx.io/materials/">Learning materials</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx">User Group</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx-dev">Developer Group</a></li>
        </ul>
      </div>

      <div class="col-xs-12 col-sm-6 col-lg-offset-2 col-md-6 copyright">
        <p>Vert.x is open source and dual licensed under the <a href="https://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License 1.0</a> and <a href="https://www.apache.org/licenses/LICENSE-2.0.html">Apache License 2.0</a>.</p>
        <p>This website is licensed under the <a href="http://creativecommons.org/licenses/by-sa/3.0/">CC BY-SA 3.0 License</a>.<br>
        Design by <a href="http://www.michel-kraemer.com">Michel Kr&auml;mer</a>. <a href="http://www.entypo.com">Entypo pictograms</a> by Daniel Bruce.</p>
        <div class="row">
          <div class="col-xs-12 col-lg-offset-1 col-md-5">
            <a href="http://eclipse.org">
            <img class="logo eclipse-logo" src="http://vertx.io/assets/eclipse_logo_grey_small.png" width="204" height="48">
            </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-0 col-md-5">
            <a href="http://cloudbees.com">
            <img class="logo cloudbees-logo" src="http://vertx.io/assets/Button-Built-on-CB-1-grey.png" width="180" height="48">
           </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-1 col-md-5 jprofiler">
            <a href="http://www.ej-technologies.com/products/jprofiler/overview.html"
            style="text-decoration:none">
            <img class="logo jprofiler-logo" src="http://vertx.io/assets/jprofiler-logo.png" width="48" height="48"><span class="jprofiler-logo">&nbsp; JPROFILER</span>
            </a>
          </div>
        </div>
      </div>
    </div>
  </div>
</footer>

<script src="http://static.jboss.org/theme/js/libs/jquery/jquery-1.9.1.min.js"></script>
<script src="http://vertx.io/javascripts/bootstrap.min.js"></script>
<script src="http://vertx.io/javascripts/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>



<script src="http://vertx.io/javascripts/sidebar.js"></script>


</body>
</html>
